home *** CD-ROM | disk | FTP | other *** search
/ Aminet 44 / Aminet 44 (2001)(GTI - Schatztruhe)[!][Aug 2001].iso / Aminet / demo / mag / GDS-DISC11b.lha / articles / instructions.txt < prev    next >
Internet Message Format  |  1998-10-02  |  15KB
  1. From: Cupid/Unique
  2. To: Evil editors of D.I.S.C (I'll get you!)
  3. Reach me at: cupid@plastique.dk
  4.  
  5. Hi! :) This text will be a how-to/tutorial on setting up an issue of D.I.S.C
  6. using my new, fabulously user-friendly diskmag engine. I'll try to be as
  7. patronizing as I can. And I'm writing this in a hurry so don't mind the
  8. tpyos, missingspaces and such. A few notes before we begin, though:
  9.  
  10.  1) The code is NOT finished. Or well, it's finished, but not final. Hmm.. 
  11.     I want to add many more features like animated clipart, transparent 
  12.     clipart, UAE protection, perhaps some background fx, a nicer pointer and
  13.     much more. It will be generally faster as well. Still, this version is 
  14.     working, and it'll do for issue 11 at least.. ehe, can't be worse than 
  15.     issue 9, can it? ;)
  16.  2) Apart from being unfinished, the engine's probably packed with bugs.
  17.     Please report them all to me.
  18.  3) The article editor was written in an extreme hurry. I KNOW it has a lot
  19.     of bugs and will crash if you try to load a picture that's bigger than
  20.     the screen and generally act weird if you're not extremely gentle with
  21.     it. :)
  22.  4) All filenames should be relative to the path of the executables, and the
  23.     executables shouldn't be moved about. This is because the engine and the
  24.     editor always expect to find clipart in gfx/, music in music/, and so 
  25.     on. And it's a little case-sensitive when it comes to filenames too.
  26.     Remember that. ;)
  27.  
  28. --------------------------  INITIALIZING EVERYTHING -------------------------
  29.  
  30. I've included some sample articles, music and gfx to give you an idea of what
  31. you can do with the mag. The panel gfx, though, were given to me long ago,
  32. supposedly drawn by Wade who's no logner drawing. There were lots of
  33. problems - first off, the lower panel may not use more than 64 colours. So I
  34. used PPaint to reduce the no. colours with F-S dithering, and it looks UGLY.
  35. What's more, the search button has to be removed if we're to use these 
  36. panels. The search function might be ready for the next issue.
  37.  
  38. Once you've enjoyed my sample mag (apart from the panels, everything is 
  39. stolen from other mags, even the fonts.. oh, except the softcore porn :),
  40. it's time to set up a new one. Backup what you want and then start off by
  41. erasing all files in gfx/, articles/, text/ and music/. fonts/ isn't really
  42. used by the mags, it just holds the fonts that have to be copied to fonts:
  43. anyway. 
  44.  
  45. -------------------------------- THE MUSIC  ------------------------------
  46.  
  47. The music is in Trackerpacker 3 format. Use the TrackerPackerV3.1 program to
  48. convert normal Protracker mods to this format and place the files (any number
  49. of files :) in the music/ directory. Now, the module that's to be played on
  50. startup has to be renamed to "default.tp3". And that's it. The other tunes
  51. are started by links, but more about that later.. :)
  52.  
  53. ------------------------------- THE FONTS ------------------------------
  54.  
  55. Right, a diskmag needs fonts, and this one needs system fonts. The mag itself
  56. only needs one font, and it's called disc.font (size 8). It may be
  57. proportional or fixed-width, doesn't matter. This is the font used for
  58. displaying the title of the current article etc. Articles may use the same
  59. font, or any other fonts you want them to.
  60.  
  61. ---------------------------- THE TITLE PICTURE ------------------------------
  62.  
  63. The engine always reads the file called gfx/title.gif to get the titlepicture.
  64. The file must be 320x256, 640x256 or 640x512.. this is so the mag will be able
  65. to determine the appropriate screenmode. If this is very inconvenient (e.g. 
  66. you have a picture that uses overscan or a 320x512 mode), let me know. Needless
  67. to say, it has to be a valid GIF file. Up to 256 cols are allowed in the title
  68. picture. No HAM. ;)
  69.  
  70. ------------------------------- THE PANELS ------------------------------
  71.  
  72. Both the editor and the mag require that the panels are present. This is a
  73. little complicated, so pay attention. :) Each panel is a GIF animation of two
  74. frames. The first frame contains the entire panel with buttons and all, and
  75. the second contains pictures of the buttons when they're pressed. Each panel
  76. is accompanied by a mask file which tells the mag where the buttons are 
  77. located.
  78.  
  79. The sizes of the panels determine the height of the article space between 
  80. them.
  81.  
  82. Let's start with the top panel, called gfx/panel1.gif, with the mask file
  83. being gfx/panel1mask.gif. Both of these files may use up to 256 cols, but the
  84. mask file only needs 4 so.. :) The top panel contains 1 button (quit) but has
  85. an additional mask that shapes the area where the title of the current 
  86. article and the page number is printed (this text uses colour 1 of the 
  87. upper panel's palette). This second mask should be at least 16 pixels tall.
  88. Look at the samples I included (you didn't erase them did you? ;), and you
  89. should get the picture. If not, you know where to reach me. Anyway, the masks
  90. for panel 1 have the following meanings:
  91.  
  92. Colour 1 - quit button
  93. Colour 2 - title field
  94.  
  95. The second panel works just like the first one, only with different buttons.
  96. Oh, and the lower panel can NOT use more than 64 colours. This sucks, I know,
  97. but it's the price you pay for the nifty scroller. :) panel2.gif holds the
  98. two frames of gfx and panel2mask.gif defines the buttons:
  99.  
  100. Colour 1 - prefs button (go to articles/prefs article, see later)
  101. Colour 2 - menu button (go to articles/menu article, see later)
  102. Colour 3 - next article
  103. Colour 4 - previous article
  104. Colour 5 - previous page
  105. Colour 6 - next page
  106. Colour 7 - search button (not used, should be left out)
  107.  
  108. How you position the buttons and how big the panels get doesn't matter, just
  109. remember, 64 cols for the lower panel and both panels must be 640 pixels 
  110. wide. Oh, and apart from the title picture, the mag runs in hires
  111. non-interlaced mode, so make sure all the gfx are in 1:2 aspect. Ah, and I
  112. almost forgot, both frames of animation must use the same palette or you'll
  113. get an "invalid GIF" error.
  114.  
  115. I recommend using PPaint to make the animated GIFs.
  116.  
  117. --------------- MAKING AN EMPTY ARTICLE FOR NO APPARENT REASON -----------------
  118.  
  119. Ok, now that the panels are in place you can start the article editor. Type
  120.  
  121. editarticle articles/menu "Main Menu"
  122.  
  123. And the editor appears. It looks ugly. :) So press the S (save) button and hit 
  124. ESC. This will create an empty article called articles/menu with the title
  125. "Main Menu".
  126.  
  127. Now, load up an ASCII editor and create a file called articles/order. Write 
  128. "articles/menu" (without the quotation marks) on the first line, save the file
  129. and exit.
  130.  
  131. You should be able to start the diskmag, ie. if everything went right with the
  132. panels and all. Don't try to press any of the buttons (except the quit button)
  133. though. :)
  134.  
  135. Create another article by typing
  136.  
  137. editarticle articles/prefs "Preferences"
  138.  
  139. Press S and ESC to save and exit without doing anything.
  140.  
  141. Now load up the articles/order file again and write "articles/prefs" on the
  142. first line (with "menu" now being on the 2nd line). It should now be safe to
  143. press all the buttons. Not that anything will happen, but.. :)
  144.  
  145. --------------------------- INSERTING CLIPART ------------------------------
  146.  
  147. Time for some clipart. Take any small GIF picture in 1:2 aspect and place it
  148. in the gfx/ dir. Be careful that it doesn't use too many colours. Hmm.. I'll
  149. try to explain this limitation: Because the mag uses attached screens, and
  150. because the inter-screen gap shouldn't be too big (it's 3 pixels now), the
  151. maximum number of colours is 64 for all screens except the upper one (the upper
  152. panel). 
  153.  
  154. The way the scroller works, two pages can actually be on the same screen at
  155. one time. And as the screen is limited to 64 colours, with 8 colours reserved 
  156. for the text and pointer, that leaves 56 cols for graphics on TWO PAGES next
  157. to one another.
  158.  
  159.                these 2 pages may use
  160.                  up to 56 cols for
  161.                      clipart
  162.                         |
  163.                   .-----------.
  164.                   |           |
  165.  
  166.   ________    ________    ________    ________    ________
  167.  |        |  |        |  |        |  |        |  |        |
  168.  |  p 1   |  |  p 2   |  |  p 3   |  |  p 4   |  | ...    |
  169.  |        |  |        |  |        |  |        |  |        |
  170.  |________|  |________|  |________|  |________|  |________|
  171.  
  172.      |            |
  173.      `------------'
  174.            |
  175.  these 2 pages may use
  176.    up to 56 cols for
  177.        clipart
  178.  
  179. And so on.. :) In other words, these conditions have to be met:
  180.  
  181. cols(page1)+cols(page2) =< 56
  182. cols(page2)+cols(page3) =< 56
  183. cols(page3)+cols(page4) =< 56
  184. etc.
  185.  
  186. Anyway, place a picture in gfx/clipart and load up the article editor by
  187. typing
  188.  
  189. editarticle articles/menu
  190.  
  191. Note that you only need to write the title when you want to change it. Now
  192. press ENTER and a requester should appear. Select the picture in this 
  193. requester and click ooohkaaay.. you should get a rectangle that you can
  194. move about with the mouse. Place it somewhere nice and press S to save the
  195. article, then ESC to quit. You needn't bother with remapping the palette,
  196. the mag handles that automagically.
  197.  
  198. Start DISC to see if it worked.
  199.  
  200. ----------------------------- INSERTING TEXT -------------------------------
  201.  
  202. Text is more complicated.. and an important thing to note is that the text
  203. routines are extremely bad :).. they'll be rewritten eventually, and all
  204. of the stupid limitations in this version will be gone. :)
  205.  
  206. Use an ASCII editor to create a file, let's call it text/pik, it's not
  207. important, as long as it's in the dir text/, or the mag will get all
  208. confused and scared. This is a quick example of how the file could look:
  209.  
  210. disc.font,8
  211. «c5»Hello M8.. this is text.. blah blah..«»
  212. This is the second line«»
  213. «e»
  214.  
  215. The first line of each file in text/ selects the font. The «c5» is the
  216. command (there are more of these, see L8R) that sets the colour, in this
  217. case to colour 5. On the rest of the line is some text, and the line is
  218. terminated by «», which forces a linefeed. A normal linefeed is interpreted
  219. as a space. This makes it easy to setup article text. It really does. :)
  220. «e» ends the article.
  221.  
  222. These are all the commands:
  223.  
  224.     «» - end of paragraph. The line is terminated and not stretched to
  225.          reach both margins if «as» has been selected.
  226.  
  227.     «e» - end of file. This must be present or bad things will happen. It
  228.           must be preceded by a «» or the last line of text will vanish.
  229.  
  230.     «t?» - produce ? non-adjusted spaces. Only really valid at the 
  231.            beginning of a paragraph.
  232.  
  233.     «al» - left-justified text from this line forward.
  234.  
  235.     «ar» - right-justified text from this line forward.
  236.  
  237.     «as» - text is stretched to reach both margins from this line 
  238.            forward.
  239.  
  240.     «ac» - centered text from this line forward.
  241.  
  242.     «c?» - set colour # ?. These colours are valid:
  243.            0 - black
  244.            1 - grey
  245.            2 - white
  246.            3 - flashing (i like this one :)
  247.            4 - blueish
  248.            5 - brighter blueish
  249.            6 - user defined colour 1 (see below)
  250.            7 - user defined colour 2
  251.  
  252.     «s?=??,???,????» - set colour ? to the RGB value (??,???,????). Only do
  253.                        this with colours 6 and 7. 
  254.  
  255.     «l:???» - link to file named ???. See below.
  256.  
  257.     «le» - end link. See below.
  258.  
  259. About colours: each word can only use one colour because the mag prints them
  260. one at a time. The colour has to be set at the beginning of each word. If 
  261. you try to do this:
  262.  
  263.   «c1»Oh my god, they killed Kenny!«c2» You Bastards!«»
  264.  
  265. Then the word "Kenny!" will be printed in colour two. You need to do this:
  266.  
  267.   «c1»Oh my god, they killed Kenny! «c2»You Bastards!«»
  268.  
  269. This is a PITA if you want one word in a specific colour, and it's followed 
  270. by a comma which has to be in another colour (not possible). But hey, gimme
  271. money and I'll fix it. 8)
  272.  
  273. About links: DISC uses an object-oriented hypertext navigation system ;D
  274. It's used a lot like in e.g. HTML:
  275.  
  276.   This paragraph contains a link - if you click
  277.   «l:articles/otherarticle»here«le», you'll go to another article.«»
  278.  
  279. There is no recursion though. You cannot retrace your steps. So it's not 
  280. really a hypertext system :). But it's just as good. The texts for the
  281. menu article would contain entries like this:
  282.  
  283. «l:articles/why_pcs_suck»Why PC's suck, a poem by Cupid«le»«»
  284. «l:articles/im_horny»I am horny, another poem by Cupid«le»«»
  285. «l:articles/x_files_crap»The truth is out there«le»«»
  286.  
  287. Putting links to articles in other places is possible but probably a bad
  288. idea. :) You may link to other things too. So far I'm only supporting
  289. music, but I could add full-screen images, or perhaps executables etc.
  290. if necessary - just ask. To link to a module, you do the same:
  291.  
  292. «l:music/idunno.tp3»Another silly module by Cupid«le»
  293.  
  294. When you click this, that module will start playing. This is for use in the
  295. prefs article primarily.
  296.  
  297. Don't forget the «le» code. If a link isn't terminated, you'll get a
  298. 'link within link' error, or the link will never become active, or worse :).
  299. A link may not span two different lines or frames. If you think this is 
  300. inconvenient, let me know, and I'll tell you why I don't give a fuck. ;)
  301.  
  302. If this made no sense to you, see the example stuff I sent, or contact me.
  303.  
  304. Okay, to insert your text file in an article, you load up the article
  305. editor and press ENTER again. In the requester, select text/pik or whatever
  306. you called it, and it'll appear in the upper-left corner of the editor.
  307. Because this is a text file, it can be resized as well as moved about. Don't
  308. mind the flickering, it's supposed to do that =).. hmmm... place it where
  309. you like, save the article, and exit. If all went well the article now has
  310. a bit of text.. :)
  311.  
  312. --------------------------- THE ARTICLE EDITOR -----------------------------
  313.  
  314. I might as well explain this now. The following keys (should) work in the
  315. editor:
  316.  
  317.   S      - save article
  318.   ESC    - exit
  319.   RIGHT  - go to next page
  320.   LEFT   - go to previous page
  321.   D      - delete current page
  322.   P      - append page
  323.   I      - insert page
  324.   ENTER  - add frame (text or gfx)
  325.   DEL    - delete frame under cursor
  326.  
  327. The order in which frames are created is important. If you want to add a
  328. background picture, for instance, it has to be the first thing you add to
  329. the page, or it'll be drawn on top of something else. Text is written in
  330. frames in the order in which the frames are created. Ie. if you want a
  331. text file to span more than one frame, the first part of the text will
  332. appear in the frame that's created first.
  333.  
  334. --------------------------- THE ORDER OF ARTICLES ------------------------
  335.  
  336. When paging through the articles, the mag needs to know the order in which
  337. they should be shown. So put ALL the articles in the articles/order file.
  338.  
  339. There.
  340.  
  341. Hmm... I probably left out something really important, but I check my email
  342. regularly, so write if there's anything. Ciao.